/*-------------------------------------------------------------------------
 *
 * posix_sema.c
 *	  使用 POSIX 信号量设施实现 PGSemaphores
 *
 * 我们更倾向于使用无名风格的 POSIX 信号量（通过 sem_init 创建的类型）。
 * 不过，我们也可以处理通过 sem_open 创建的类型。
 *
 * 在任一实现中，typedef PGSemaphore 等同于“sem_t *”。
 * 使用无名信号量时，sem_t 结构体存放在共享内存中的一个数组中。
 * 使用命名信号量时，并非如此，因为我们无法说服 sem_open 在那里进行分配。
 * 因此，命名信号量代码 *不处理 EXEC_BACKEND*。sem_t 结构体将只在
 * 后台管理器的私有内存中，成功地被派生的子进程继承，但执行的子进程无法访问。
 *
 *
 * Portions Copyright (c) 1996-2022, PostgreSQL Global Development Group
 * Portions Copyright (c) 1994, Regents of the University of California
 *
 * IDENTIFICATION
 *	  src/backend/port/posix_sema.c
 *
 *-------------------------------------------------------------------------
 */
#include "postgres.h"

#include <fcntl.h>
#include <semaphore.h>
#include <signal.h>
#include <unistd.h>
#include <sys/stat.h>

#include "miscadmin.h"
#include "storage/ipc.h"
#include "storage/pg_sema.h"
#include "storage/shmem.h"


/* 查看文件头注释 */
#if defined(USE_NAMED_POSIX_SEMAPHORES) && defined(EXEC_BACKEND)
#error cannot use named POSIX semaphores with EXEC_BACKEND
#endif

typedef union SemTPadded
{
	sem_t		pgsem;
	char		pad[PG_CACHE_LINE_SIZE];
} SemTPadded;

/* typedef PGSemaphore 相当于指向 sem_t 的指针 */
typedef struct PGSemaphoreData
{
	SemTPadded	sem_padded;
} PGSemaphoreData;

#define PG_SEM_REF(x)	(&(x)->sem_padded.pgsem)

#define IPCProtection	(0600)	/* 仅用户可访问/修改 */

#ifdef USE_NAMED_POSIX_SEMAPHORES
static sem_t **mySemPointers;	/* 记录创建的信号量 */
#else
static PGSemaphore sharedSemas; /* 共享内存中的 PGSemaphoreData 数组 */
#endif
static int	numSems;			/* 到目前为止已获取的信号量数量 */
static int	maxSems;			/* 上述数组的分配大小 */
static int	nextSemKey;			/* 下一个尝试的名称 */


static void fc_ReleaseSemaphores(int fc_status, Datum fc_arg);


#ifdef USE_NAMED_POSIX_SEMAPHORES

/*
 * PosixSemaphoreCreate
 *
 * 尝试创建一个新的命名信号量。
 *
 * 如果我们以非与现有信号量冲突的失败代码失败，
 * 打印出错误并中止。其他类型的错误暗示不可恢复
 * 的问题。
 */
static sem_t *
PosixSemaphoreCreate(void)
{
	int			fc_semKey;
	char		fc_semname[64];
	sem_t	   *fc_mySem;

	for (;;)
	{
		fc_semKey = nextSemKey++;

		snprintf(fc_semname, sizeof(fc_semname), "/pgsql-%d", fc_semKey);

		fc_mySem = sem_open(fc_semname, O_CREAT | O_EXCL,
						 (mode_t) IPCProtection, (unsigned) 1);

#ifdef SEM_FAILED
		if (fc_mySem != (sem_t *) SEM_FAILED)
			break;
#else
		if (fc_mySem != (sem_t *) (-1))
			break;
#endif

		/* 如果错误指示冲突，则循环 */
		if (errno == EEXIST || errno == EACCES || errno == EINTR)
			continue;

		/*
		 * 否则抱怨并中止
		 */
		elog(FATAL, "sem_open(\"%s\") failed: %m", fc_semname);
	}

	/*
	 * 立即解除信号量的链接，以便不能被外部访问。
	 * 这也确保如果我们崩溃，它会消失。
	 */
	sem_unlink(fc_semname);

	return fc_mySem;
}
#else							/* !USE_NAMED_POSIX_SEMAPHORES */

/*
 * PosixSemaphoreCreate
 *
 * 尝试创建一个新的未命名信号量。
 */
static void fc_PosixSemaphoreCreate(sem_t *fc_sem)
{
	if (sem_init(fc_sem, 1, 1) < 0)
		elog(FATAL, "sem_init failed: %m");
}
#endif							/* USE_NAMED_POSIX_SEMAPHORES */


/*
 * PosixSemaphoreKill - 移除一个信号量
 */
static void fc_PosixSemaphoreKill(sem_t *fc_sem)
{
#ifdef USE_NAMED_POSIX_SEMAPHORES
	/* 对于命名信号量必须使用 sem_close */
	if (sem_close(fc_sem) < 0)
		elog(LOG, "sem_close failed: %m");
#else
	/* 对于未命名信号量必须使用 sem_destroy */
	if (sem_destroy(fc_sem) < 0)
		elog(LOG, "sem_destroy failed: %m");
#endif
}


/*
 * 报告信号量所需的共享内存量
 */
Size PGSemaphoreShmemSize(int fc_maxSemas)
{
#ifdef USE_NAMED_POSIX_SEMAPHORES
	/* 在这种情况下不需要共享内存 */
	return 0;
#else
	/* 每个信号量需要一个 PGSemaphoreData */
	return mul_size(fc_maxSemas, sizeof(PGSemaphoreData));
#endif
}

/*
 * PGReserveSemaphores --- 初始化信号量支持
 *
 * 这在主进程启动或共享内存重新初始化期间被调用。
 * 它应该做任何必要的事情，以支持最多 maxSemas
 * 后续的 PGSemaphoreCreate 调用。此外，如果在这里或在
 * PGSemaphoreCreate 中获取了任何系统资源，请注册一个
 * on_shmem_exit 回调以释放它们。
 *
 * 在 Posix 实现中，我们按需获取信号量；
 * maxSemas 参数仅用于定义数组大小。对于未命名
 * 信号量，共享内存中有一个 PGSemaphoreData 结构体数组。
 * 对于命名信号量，我们保留一个主进程本地的 sem_t 指针数组，
 * 在完成时用于释放信号量。
 * （该设计最小化了主进程关闭依赖于
 * 共享内存内容的可能性，而失败的后端可能会破坏这些内容。
 * 我们无法对此做太多，但我们不必将计数器暴露给其他进程。）
 */
void PGReserveSemaphores(int fc_maxSemas)
{
	struct stat fc_statbuf;

	/*
	 * 我们使用数据目录的 inode 号来为寻找空闲
	 * 信号量键提供种子。这最小化了与其他
	 * 主进程冲突的几率，同时最大化了我们检测和清理
	 * 残留在自己目录中的崩溃主进程留下的信号量的几率。
	 */
	if (stat(DataDir, &fc_statbuf) < 0)
		ereport(FATAL,
				(errcode_for_file_access(),
				 errmsg("could not stat data directory \"%s\": %m",
						DataDir)));

#ifdef USE_NAMED_POSIX_SEMAPHORES
	mySemPointers = (sem_t **) malloc(fc_maxSemas * sizeof(sem_t *));
	if (mySemPointers == NULL)
		elog(PANIC, "out of memory");
#else

	/*
	 * 我们必须使用 ShmemAllocUnlocked()，因为保护
	 * ShmemAlloc() 的自旋锁还未准备好。（当我们
	 * 用信号量模拟自旋锁时需要这种顺序。）
	 */
	sharedSemas = (PGSemaphore)
		ShmemAllocUnlocked(PGSemaphoreShmemSize(fc_maxSemas));
#endif

	numSems = 0;
	maxSems = fc_maxSemas;
	nextSemKey = fc_statbuf.st_ino;

	on_shmem_exit(fc_ReleaseSemaphores, 0);
}

/*
 * 在关闭或共享内存重新初始化时释放信号量
 *
 * （作为 on_shmem_exit 回调被调用，因此参数列表有点奇怪）
 */
static void fc_ReleaseSemaphores(int fc_status, Datum fc_arg)
{
	int			fc_i;

#ifdef USE_NAMED_POSIX_SEMAPHORES
	for (fc_i = 0; fc_i < numSems; fc_i++)
		PosixSemaphoreKill(mySemPointers[fc_i]);
	free(mySemPointers);
#endif

#ifdef USE_UNNAMED_POSIX_SEMAPHORES
	for (fc_i = 0; fc_i < numSems; fc_i++)
		fc_PosixSemaphoreKill(PG_SEM_REF(sharedSemas + fc_i));
#endif
}

/*
 * PGSemaphoreCreate
 *
 * 分配一个初值为1的PGSemaphore结构
 */
PGSemaphore PGSemaphoreCreate(void)
{
	PGSemaphore fc_sema;
	sem_t	   *fc_newsem;

	/* 在后端无法执行此操作，因为静态状态属于主进程 */
	Assert(!IsUnderPostmaster);

	if (numSems >= maxSems)
		elog(PANIC, "too many semaphores created");

#ifdef USE_NAMED_POSIX_SEMAPHORES
	fc_newsem = PosixSemaphoreCreate();
	/* 记住新的信号量以供ReleaseSemaphores使用 */
	mySemPointers[numSems] = fc_newsem;
	fc_sema = (PGSemaphore) fc_newsem;
#else
	fc_sema = &sharedSemas[numSems];
	fc_newsem = PG_SEM_REF(fc_sema);
	fc_PosixSemaphoreCreate(fc_newsem);
#endif

	numSems++;

	return fc_sema;
}

/*
 * PGSemaphoreReset
 *
 * 将先前初始化的PGSemaphore重置为计数0
 */
void PGSemaphoreReset(PGSemaphore fc_sema)
{
	/*
	 * 在POSIX中没有直接的API来实现这一点，因此我们必须通过重复的trywait将
	 * 信号量减少到0。
	 */
	for (;;)
	{
		if (sem_trywait(PG_SEM_REF(fc_sema)) < 0)
		{
			if (errno == EAGAIN || errno == EDEADLK)
				break;			/* 已将其降到0 */
			if (errno == EINTR)
				continue;		/* 这可能发生吗？ */
			elog(FATAL, "sem_trywait failed: %m");
		}
	}
}

/*
 * PGSemaphoreLock
 *
 * 锁定一个信号量（减少计数），如果计数会变为< 0则阻塞
 */
void PGSemaphoreLock(PGSemaphore fc_sema)
{
	int			fc_errStatus;

	/* 请参见sysv_sema.c中PGSemaphoreLock的实现中的说明。 */
	do
	{
		fc_errStatus = sem_wait(PG_SEM_REF(fc_sema));
	} while (fc_errStatus < 0 && errno == EINTR);

	if (fc_errStatus < 0)
		elog(FATAL, "sem_wait failed: %m");
}

/*
 * PGSemaphoreUnlock
 *
 * 解锁一个信号量（增加计数）
 */
void PGSemaphoreUnlock(PGSemaphore fc_sema)
{
	int			fc_errStatus;

	/*
	 * 注意：如果errStatus为-1且errno == EINTR，则意味着我们
	 * 因为收到了信号而提前从操作中返回。因此我们再次尝试解锁信号量。
	 * 目前不清楚这种情况是否会真的发生，但还是要做好应对。
	 */
	do
	{
		fc_errStatus = sem_post(PG_SEM_REF(fc_sema));
	} while (fc_errStatus < 0 && errno == EINTR);

	if (fc_errStatus < 0)
		elog(FATAL, "sem_post failed: %m");
}

/*
 * PGSemaphoreTryLock
 *
 * 仅在能够而不阻塞的情况下锁定信号量
 */
bool PGSemaphoreTryLock(PGSemaphore fc_sema)
{
	int			fc_errStatus;

	/*
	 * 注意：如果errStatus为-1且errno == EINTR，则意味着我们
	 * 因为收到了信号而提前从操作中返回。因此我们再次尝试锁定信号量。
	 */
	do
	{
		fc_errStatus = sem_trywait(PG_SEM_REF(fc_sema));
	} while (fc_errStatus < 0 && errno == EINTR);

	if (fc_errStatus < 0)
	{
		if (errno == EAGAIN || errno == EDEADLK)
			return false;		/* 锁定失败 */
		/* 否则我们会有麻烦 */
		elog(FATAL, "sem_trywait failed: %m");
	}

	return true;
}
